Consolidate DDSQL references #28821

estherk15 · 2025-04-16T21:04:09Z

What does this PR do? What is the motivation?

This PR consolidates the DDSQL references for Workspaces and the DDSQL Editor into a single resource page.

DOCS-10588

🧩 Problem this solves:

There are currently two DDSQL references for two Preview products, each with different levels of syntax support. This has led to confusion, as customers often mix up which syntax applies to which product.
While this currently affects only a few hundred customers, Workspaces is expected to GA by the end of the month, and the confusion will scale.
Creating a single entry point for DDSQL information should reduce misinterpretation and help customers get to the right syntax faster.
This also aligns with future plans to maintain a single, unified DDSQL reference.

What to look for during review:

If you were a new user, would it be clear which syntax applies to your product?
Do all links and aliases point to the correct DDSQL documentation?
The content itself hasn't changed, but an alert box was added to clarify that there are two versions of DDSQL, and to guide users to the correct one based on their product.

Merge instructions

Merge readiness:

Ready for merge

For Datadog employees:
Merge queue is enabled in this repo. Your branch name MUST follow the <name>/<description> convention and include the forward slash (/). Without this format, your pull request will not pass in CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.

If your branch doesn't follow this format, rename it or create a new branch and PR.

To have your PR automatically merged after it receives the required reviews, add the following PR comment:

/merge

Additional notes

github-actions · 2025-04-16T21:07:29Z

Preview links (active after the `build_preview` check completes)

New or renamed files

Removed or renamed files (these should redirect)

https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_editor/guide/

Renamed files

Modified Files

janine-c

Hey Esther! This looks like a gigantic chonk of work; nice job!

I left some minor comments; let me know if you have any questions 🙂 Overall, I think this is a bit of a tough nut to crack if you aren't already familiar with what's happening (what am I saying, I'm clearly talking about myself 😂). The current docs make it sound like the SQL reference is just generic SQL, which makes the new labelling of DDSQL a bit confusing - is it the same SQL someone might learn at another company, or is it now something unique to us? I don't know enough about it to make a call!

I also struggled to understand why the DDSQL Editor content was split between the DDSQL and DDSQL Editor sections in the left nav - I don't understand enough about why they're different, and struggled to intuit why some content would be in one section or the other. I wonder if if renaming DDSQL to DDSQL Reference might help clear that up? Again, I'm not entirely sure what's right based on the problem we're solving here.

Lastly, while I don't think there's anything with the disclaimers you added in this PR, I think the framing is different from what you described in the PR description, so I thought I'd bring it up. The disclaimers frame this distinction as a matter of support, and kind of gloss over the fact that there are two versions of DDSQL - it kind of maybe sounds like the differences are quite minor. Your description here frames it around two versions of DDSQL, which isn't really mentioned in the disclaimers, which also makes the differences sound more significant and important to understand! I think I prefer the explicit "hey, there are two different versions with different support" angle, rather than the "the DDSQL Editor might not support some syntax" angle, if that makes sense?

Again, let me know if you'd like to chat about this more. It seems like a lot to understand, and that can be tough to express in the docs. But you've done a great job so far!

content/en/ddsql/ddsql_editor_syntax.md

content/en/ddsql/_index.md

content/en/ddsql/ddsql_default.md

content/en/ddsql/ddsql_editor_syntax/window_functions.md

content/en/ddsql/ddsql_editor_syntax.md

content/en/ddsql/ddsql_editor_syntax/window_functions.md

content/en/ddsql_editor/reference_tables.md

content/en/ddsql_editor/tags.md

jinatdatadog · 2025-04-17T00:36:51Z

Could we make "DDSQL Editor Syntax (Preview)" --> "DDSQL v0 (for DDSQL Editor Preview)"
And "DDSQL for the DDSQL Editor" --> "DDSQL v0"?

Can we also remove this banner in the "DDSQL for the DDSQL Editor" tab? Its redundant, since the banner is already in the "DDSQL" tab

Thanks for this!

Co-authored-by: Janine Chan <[email protected]>

content/en/ddsql/_index.md

content/en/ddsql/ddsql_editor_syntax.md

TylerMills · 2025-04-17T15:11:19Z

For the tabs, what do we think about:

v1
v0 (Preview)

I do think that putting 'DDSQL Editor' in tabs might cause more confusion though since DDSQL Editor will have v1 eventually. @jinatdatadog

- Remove disclaimer from DDSQL Editor Syntax docs - Rephrase disclaimer to be transparent about the two different variants of DDSQL and direct customers to the relevant docs - Rename DDSQL to DDSQL Reference to distinguish between DDSQL Editor - Update URLs for DDSQL Reference - Update tabs to DDSQL Editor Syntax (Preview) and specify DDSQL Editor for all child pages

content/en/ddsql_editor/_index.md

estherk15 · 2025-04-18T17:20:31Z

For the tabs, what do we think about:

v1

v0 (Preview)

I do think that putting 'DDSQL Editor' in tabs might cause more confusion though since DDSQL Editor will have v1 eventually. @jinatdatadog

@TylerMills @jinatdatadog @janine-c
Thanks for the feedback! I see the reasoning behind using V0/V1 to differentiate the two DDSQL syntaxes and trying to reduce confusion when DDSQL supports eventually "V1" syntax. I opted for DDSQL and DDSQL Editor Syntax (Preview) because version labels feel like implementation details the docs should abstract away, especially since the syntaxes aren’t strictly linear or backward-compatible. Product-specific labels reflect the current user experience and help users self-identify the right reference.

As DDSQL Editor begins to adopt the broader syntax, we can revisit the framing to ensure the docs stay intuitive and accurate for customers!

TylerMills · 2025-04-22T17:40:43Z

@estherk15 "As DDSQL Editor begins to adopt the broader syntax, we can revisit the framing to ensure the docs stay intuitive and accurate for customers!"

I think the plan is to start exposing this in the next week or so (but will run in parallel with old version) so I think these tabs are still confusing.

estherk15 · 2025-04-22T19:11:09Z

@TylerMills Thanks for the additional context. How long do you plan to run these in parallel and which features are you enabling for customers? Or is it just that customers can either use the DDSQL Editor syntax vs. Workspaces syntax? How are you communicating this to DDSQL Editor users?

jinatdatadog · 2025-04-23T20:11:22Z

@estherk15 we'll have the appropriate in-app enablement/documentation for DDSQL Editor customers. The plan is to allow them to use both syntax in DDSQL Editor from DASH for ~2 months. After that we'll do a hard cutover where all DDSQL Editor customers are using DDSQL (and not DDSQL Editor Preview Syntax)

I can reach out when we do that hard cutover to have the DDSQL Editor Preview Syntax deprecated

urseberry · 2025-04-23T22:24:13Z

How does the user know which syntax they are using in the app? Do V0 and V1 appear in the app?

TylerMills · 2025-04-28T14:45:48Z

cc @liujuliet

I think if we have the tabs simply say: DDSQL and Preview that might be the best.

estherk15 · 2025-04-28T15:59:30Z

@TylerMills @jinatdatadog Thank you for the context and feedback! The tabs are now labeled DDSQL and DDSQL (Preview).
Is this ready to publish, or is anything else still pending?

janine-c

This is looking really good, Esther! I'm finding it a lot simpler to navigate and understand. My main concern here is with making it clear which syntax version the guides are targeting, but once we've got that cleared up, I think we're ready to 🎉

content/en/ddsql_reference/_index.md

content/en/ddsql_reference/ddsql_default.md

content/en/ddsql_reference/ddsql_preview.md

content/en/ddsql_reference/ddsql_preview/reference_tables.md

content/en/ddsql_reference/ddsql_preview/tags.md

content/en/logs/workspaces/_index.md

Co-authored-by: Janine Chan <[email protected]>

NGA-TRAN

LGTM. Most are document files.
Where are the two yaml files used? Have you run this on staging? Maybe try it first (if not yet) to avoid unexpected behavior

NGA-TRAN · 2025-05-02T20:04:33Z

content/en/ddsql_reference/_index.md

+
+## Supported DDSQL Syntax
+
+DDSQL is a query language for Datadog data. It implements several standard SQL operations, such as `SELECT`, and allows queries against unstructured data, such as [tags][1]. You can perform actions like getting exactly the data you want by writing your own `SELECT` statement, or querying tags as if they are standard table columns.


Nice description

NGA-TRAN · 2025-05-02T20:06:58Z

content/en/ddsql_reference/ddsql_default.md

@@ -219,23 +234,23 @@ SELECT
 ### `TRIM`
 {{< code-block lang="sql" >}}
 SELECT
-  TRIM(name) AS trimmed_name
+  trim(name) AS trimmed_name


Nit: Since SQL is not case sensitive, it is find to make this lowercase. However, it is nice to keep them upper case as they are functions/keywords

urseberry

Amazing work, Esther. Thank you for listening to the many voices weighing in on this change. I find the end result very clear, and I think the users will appreciate it!

Left some non-blocking feedback above on the order of menu items.

urseberry · 2025-05-08T21:56:58Z

config/_default/menus/main.en.yaml

@@ -1184,7 +1184,7 @@ menu:
      pre: cloudcraft
      identifier: cloudcraft
      parent: essentials_heading
-      weight: 270000
+      weight: 130000


I think the old 270000 value was intentional to put Cloudcraft at the bottom of the menu. I probably would have left Cloudcraft at 270000. DDSQL Reference could maybe even be above CoScreen and CoTerm, although then you have to make even more changes.

Thanks for the Cloudcraft context, moved DDSQL Reference up!

estherk15 added 2 commits April 16, 2025 16:33

Move DDSQL syntax guides to Essentials

de5506a

Move workspaces reference to ddsql

0d154ee

estherk15 requested review from a team as code owners April 16, 2025 21:04

github-actions bot added the Architecture Everything related to the Doc backend label Apr 16, 2025

Add reference to the workspaces index

b4605ee

estherk15 changed the title ~~Esther/docs 10588 ddsql reference~~ Consolidate DDSQL references Apr 16, 2025

janine-c reviewed Apr 16, 2025

View reviewed changes

Apply suggestions from code review

a2cd50b

Co-authored-by: Janine Chan <[email protected]>

estherk15 commented Apr 17, 2025

View reviewed changes

content/en/ddsql/_index.md Outdated Show resolved Hide resolved

content/en/ddsql/_index.md Outdated Show resolved Hide resolved

content/en/ddsql/ddsql_editor_syntax.md Outdated Show resolved Hide resolved

content/en/ddsql/ddsql_editor_syntax.md Outdated Show resolved Hide resolved

urseberry reviewed Apr 18, 2025

View reviewed changes

content/en/ddsql_editor/_index.md Outdated Show resolved Hide resolved

Apply code review suggestion

437c77d

estherk15 added 2 commits April 28, 2025 10:48

Merge branch 'master' into esther/docs-10588-ddsql-reference

4a9646f

Rename to DDSQL Preview

a30d753

estherk15 added the okr11 label Apr 28, 2025

estherk15 added 2 commits April 30, 2025 17:44

Move DDSQL Tags and Reference Tables docs out of DDSQL Editor

f92290e

Revise codeowners and move guides

d697648

estherk15 requested a review from a team as a code owner April 30, 2025 22:06

github-actions bot added Github Related to Github configurations Guide Content impacting a guide labels Apr 30, 2025

estherk15 requested review from janine-c and jinatdatadog April 30, 2025 22:12

janine-c reviewed May 1, 2025

View reviewed changes

estherk15 and others added 6 commits May 1, 2025 10:43

Apply suggestions from code review

4a51c13

Co-authored-by: Janine Chan <[email protected]>

Code review remove Editor from Preview docs and add product availability

c793566

Remove Editor reference from Window functions

629151a

Clarify Preview syntax for guides

4336f6a

Merge branch 'master' into esther/docs-10588-ddsql-reference

2d78849

Add Preview note to use cases

8c2611a

NGA-TRAN approved these changes May 2, 2025

View reviewed changes

StefonSimmons approved these changes May 2, 2025

View reviewed changes

Merge branch 'master' into esther/docs-10588-ddsql-reference

aa153ad

estherk15 requested a review from janine-c May 7, 2025 01:46

Capitalize function names for SQL Reference

077968d

jinatdatadog approved these changes May 8, 2025

View reviewed changes

urseberry approved these changes May 8, 2025

View reviewed changes

Update menu

00fa144

estherk15 merged commit a6d3ff8 into master May 9, 2025
12 of 13 checks passed

estherk15 deleted the esther/docs-10588-ddsql-reference branch May 9, 2025 14:16


		## Supported DDSQL Syntax

		DDSQL is a query language for Datadog data. It implements several standard SQL operations, such as `SELECT`, and allows queries against unstructured data, such as [tags][1]. You can perform actions like getting exactly the data you want by writing your own `SELECT` statement, or querying tags as if they are standard table columns.

Consolidate DDSQL references #28821

Consolidate DDSQL references #28821

Uh oh!

Conversation

estherk15 commented Apr 16, 2025 • edited by jira bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do? What is the motivation?

🧩 Problem this solves:

What to look for during review:

Merge instructions

Additional notes

Uh oh!

github-actions bot commented Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview links (active after the build_preview check completes)

New or renamed files

Removed or renamed files (these should redirect)

Renamed files

Modified Files

Uh oh!

janine-c left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jinatdatadog commented Apr 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TylerMills commented Apr 17, 2025

Uh oh!

Uh oh!

estherk15 commented Apr 18, 2025

Uh oh!

TylerMills commented Apr 22, 2025

Uh oh!

estherk15 commented Apr 22, 2025

Uh oh!

jinatdatadog commented Apr 23, 2025

Uh oh!

urseberry commented Apr 23, 2025

Uh oh!

TylerMills commented Apr 28, 2025

Uh oh!

estherk15 commented Apr 28, 2025

Uh oh!

janine-c left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NGA-TRAN left a comment

Choose a reason for hiding this comment

Uh oh!

NGA-TRAN May 2, 2025

Choose a reason for hiding this comment

Uh oh!

NGA-TRAN May 2, 2025

Choose a reason for hiding this comment

Uh oh!

urseberry left a comment

Choose a reason for hiding this comment

Uh oh!

urseberry May 8, 2025

Choose a reason for hiding this comment

estherk15 commented Apr 16, 2025 •

edited by jira bot

Loading

github-actions bot commented Apr 16, 2025 •

edited

Loading

Preview links (active after the `build_preview` check completes)